<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>What’s New or Different &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Random sampling (numpy.random)" href="index.html" >
    <link rel="next" title="Performance" href="performance.html" >
    <link rel="prev" title="Multithreaded Generation" href="multithreading.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../routines.html" >Routines</a></li>
          <li class="active"><a href="index.html" accesskey="U">Random sampling (<code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.random</span></code>)</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="performance.html" title="Performance"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="multithreading.html" title="Multithreaded Generation"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="multithreading.html"
                        title="previous chapter">Multithreaded Generation</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="performance.html"
                        title="next chapter">Performance</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="what-s-new-or-different">
<span id="new-or-different"></span><h1>What’s New or Different<a class="headerlink" href="#what-s-new-or-different" title="Permalink to this headline">¶</a></h1>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The Box-Muller method used to produce NumPy’s normals is no longer available
in <a class="reference internal" href="generator.html#numpy.random.Generator" title="numpy.random.Generator"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator</span></code></a>.  It is not possible to reproduce the exact random
values using <code class="docutils literal notranslate"><span class="pre">Generator</span></code> for the normal distribution or any other
distribution that relies on the normal such as the <a class="reference internal" href="generated/numpy.random.Generator.gamma.html#numpy.random.Generator.gamma" title="numpy.random.Generator.gamma"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator.gamma</span></code></a> or
<a class="reference internal" href="generated/numpy.random.Generator.standard_t.html#numpy.random.Generator.standard_t" title="numpy.random.Generator.standard_t"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator.standard_t</span></code></a>. If you require bitwise backward compatible
streams, use <a class="reference internal" href="legacy.html#numpy.random.RandomState" title="numpy.random.RandomState"><code class="xref py py-obj docutils literal notranslate"><span class="pre">RandomState</span></code></a>, i.e., <a class="reference internal" href="generated/numpy.random.RandomState.gamma.html#numpy.random.RandomState.gamma" title="numpy.random.RandomState.gamma"><code class="xref py py-obj docutils literal notranslate"><span class="pre">RandomState.gamma</span></code></a> or
<a class="reference internal" href="generated/numpy.random.RandomState.standard_t.html#numpy.random.RandomState.standard_t" title="numpy.random.RandomState.standard_t"><code class="xref py py-obj docutils literal notranslate"><span class="pre">RandomState.standard_t</span></code></a>.</p>
</div>
<p>Quick comparison of legacy <a class="reference external" href="legacy">mtrand</a> to the new <a class="reference internal" href="generator.html#numpy.random.Generator" title="numpy.random.Generator"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator</span></code></a></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 23%" />
<col style="width: 26%" />
<col style="width: 51%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>Feature</p></td>
<td><p>Older Equivalent</p></td>
<td><p>Notes</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generator.html#numpy.random.Generator" title="numpy.random.Generator"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator</span></code></a></p></td>
<td><p><a class="reference internal" href="legacy.html#numpy.random.RandomState" title="numpy.random.RandomState"><code class="xref py py-obj docutils literal notranslate"><span class="pre">RandomState</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Generator</span></code> requires a stream
source, called a <a class="reference internal" href="bit_generators/generated/numpy.random.BitGenerator.html#numpy.random.BitGenerator" title="numpy.random.BitGenerator"><code class="xref py py-obj docutils literal notranslate"><span class="pre">BitGenerator</span></code></a>
A number of these are provided.
<code class="docutils literal notranslate"><span class="pre">RandomState</span></code> uses
the Mersenne Twister <a class="reference internal" href="bit_generators/mt19937.html#numpy.random.MT19937" title="numpy.random.MT19937"><code class="xref py py-obj docutils literal notranslate"><span class="pre">MT19937</span></code></a> by
default, but can also be instantiated
with any BitGenerator.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">random</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">random_sample</span></code>,
<code class="docutils literal notranslate"><span class="pre">rand</span></code></p></td>
<td><p>Access the values in a BitGenerator,
convert them to <code class="docutils literal notranslate"><span class="pre">float64</span></code> in the
interval <code class="docutils literal notranslate"><span class="pre">[0.0.,</span></code> `` 1.0)``.
In addition to the <code class="docutils literal notranslate"><span class="pre">size</span></code> kwarg, now
supports <code class="docutils literal notranslate"><span class="pre">dtype='d'</span></code> or <code class="docutils literal notranslate"><span class="pre">dtype='f'</span></code>,
and an <code class="docutils literal notranslate"><span class="pre">out</span></code> kwarg to fill a user-
supplied array.</p>
<p>Many other distributions are also
supported.</p>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">integers</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">randint</span></code>,
<code class="docutils literal notranslate"><span class="pre">random_integers</span></code></p></td>
<td><p>Use the <code class="docutils literal notranslate"><span class="pre">endpoint</span></code> kwarg to adjust
the inclusion or exclution of the
<code class="docutils literal notranslate"><span class="pre">high</span></code> interval endpoint</p></td>
</tr>
</tbody>
</table>
<p>And in more detail:</p>
<ul class="simple">
<li><p>Simulate from the complex normal distribution
(<em class="xref py py-obj">complex_normal</em>)</p></li>
<li><p>The normal, exponential and gamma generators use 256-step Ziggurat
methods which are 2-10 times faster than NumPy’s default implementation in
<a class="reference internal" href="generated/numpy.random.Generator.standard_normal.html#numpy.random.Generator.standard_normal" title="numpy.random.Generator.standard_normal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_normal</span></code></a>, <a class="reference internal" href="generated/numpy.random.Generator.standard_exponential.html#numpy.random.Generator.standard_exponential" title="numpy.random.Generator.standard_exponential"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_exponential</span></code></a> or
<a class="reference internal" href="generated/numpy.random.Generator.standard_gamma.html#numpy.random.Generator.standard_gamma" title="numpy.random.Generator.standard_gamma"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_gamma</span></code></a>.</p></li>
<li><p><a class="reference internal" href="generated/numpy.random.Generator.integers.html#numpy.random.Generator.integers" title="numpy.random.Generator.integers"><code class="xref py py-obj docutils literal notranslate"><span class="pre">integers</span></code></a> is now the canonical way to generate integer
random numbers from a discrete uniform distribution. The <code class="docutils literal notranslate"><span class="pre">rand</span></code> and
<code class="docutils literal notranslate"><span class="pre">randn</span></code> methods are only available through the legacy <a class="reference internal" href="legacy.html#numpy.random.RandomState" title="numpy.random.RandomState"><code class="xref py py-obj docutils literal notranslate"><span class="pre">RandomState</span></code></a>.
This replaces both <code class="docutils literal notranslate"><span class="pre">randint</span></code> and the deprecated <code class="docutils literal notranslate"><span class="pre">random_integers</span></code>.</p></li>
<li><p>The Box-Muller method used to produce NumPy’s normals is no longer available.</p></li>
<li><p>All bit generators can produce doubles, uint64s and
uint32s via CTypes (<a class="reference internal" href="bit_generators/generated/numpy.random.PCG64.ctypes.html#numpy.random.PCG64.ctypes" title="numpy.random.PCG64.ctypes"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ctypes</span></code></a>) and CFFI (<a class="reference internal" href="bit_generators/generated/numpy.random.PCG64.cffi.html#numpy.random.PCG64.cffi" title="numpy.random.PCG64.cffi"><code class="xref py py-obj docutils literal notranslate"><span class="pre">cffi</span></code></a>).
This allows these bit generators to be used in numba.</p></li>
<li><p>The bit generators can be used in downstream projects via
Cython.</p></li>
</ul>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [1]: </span><span class="kn">from</span>  <span class="nn">numpy.random</span> <span class="kn">import</span> <span class="n">Generator</span><span class="p">,</span> <span class="n">PCG64</span>

<span class="gp">In [2]: </span><span class="kn">import</span> <span class="nn">numpy.random</span>

<span class="gp">In [3]: </span><span class="n">rg</span> <span class="o">=</span> <span class="n">Generator</span><span class="p">(</span><span class="n">PCG64</span><span class="p">())</span>

<span class="gp">In [4]: </span><span class="o">%</span><span class="k">timeit</span> rg.standard_normal(100000)
<span class="gp">   ...: </span><span class="o">%</span><span class="k">timeit</span> numpy.random.standard_normal(100000)
<span class="gp">   ...: </span>
<span class="go">7.55 ms +- 692 us per loop (mean +- std. dev. of 7 runs, 100 loops each)</span>
<span class="go">21.4 ms +- 2.91 ms per loop (mean +- std. dev. of 7 runs, 10 loops each)</span>
</pre></div>
</div>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [5]: </span><span class="o">%</span><span class="k">timeit</span> rg.standard_exponential(100000)
<span class="gp">   ...: </span><span class="o">%</span><span class="k">timeit</span> numpy.random.standard_exponential(100000)
<span class="gp">   ...: </span>
<span class="go">4.58 ms +- 392 us per loop (mean +- std. dev. of 7 runs, 100 loops each)</span>
<span class="go">23 ms +- 3.61 ms per loop (mean +- std. dev. of 7 runs, 10 loops each)</span>
</pre></div>
</div>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [6]: </span><span class="o">%</span><span class="k">timeit</span> rg.standard_gamma(3.0, 100000)
<span class="gp">   ...: </span><span class="o">%</span><span class="k">timeit</span> numpy.random.standard_gamma(3.0, 100000)
<span class="gp">   ...: </span>
<span class="go">18 ms +- 1.26 ms per loop (mean +- std. dev. of 7 runs, 100 loops each)</span>
<span class="go">35.8 ms +- 6.32 ms per loop (mean +- std. dev. of 7 runs, 10 loops each)</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Optional <code class="docutils literal notranslate"><span class="pre">dtype</span></code> argument that accepts <code class="docutils literal notranslate"><span class="pre">np.float32</span></code> or <code class="docutils literal notranslate"><span class="pre">np.float64</span></code>
to produce either single or double prevision uniform random variables for
select distributions</p>
<ul>
<li><p>Uniforms (<a class="reference internal" href="generated/numpy.random.Generator.random.html#numpy.random.Generator.random" title="numpy.random.Generator.random"><code class="xref py py-obj docutils literal notranslate"><span class="pre">random</span></code></a> and <a class="reference internal" href="generated/numpy.random.Generator.integers.html#numpy.random.Generator.integers" title="numpy.random.Generator.integers"><code class="xref py py-obj docutils literal notranslate"><span class="pre">integers</span></code></a>)</p></li>
<li><p>Normals (<a class="reference internal" href="generated/numpy.random.Generator.standard_normal.html#numpy.random.Generator.standard_normal" title="numpy.random.Generator.standard_normal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_normal</span></code></a>)</p></li>
<li><p>Standard Gammas (<a class="reference internal" href="generated/numpy.random.Generator.standard_gamma.html#numpy.random.Generator.standard_gamma" title="numpy.random.Generator.standard_gamma"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_gamma</span></code></a>)</p></li>
<li><p>Standard Exponentials (<a class="reference internal" href="generated/numpy.random.Generator.standard_exponential.html#numpy.random.Generator.standard_exponential" title="numpy.random.Generator.standard_exponential"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_exponential</span></code></a>)</p></li>
</ul>
</li>
</ul>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [7]: </span><span class="n">rg</span> <span class="o">=</span> <span class="n">Generator</span><span class="p">(</span><span class="n">PCG64</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>

<span class="gp">In [8]: </span><span class="n">rg</span><span class="o">.</span><span class="n">random</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;d&#39;</span><span class="p">)</span>
<span class="gh">Out[8]: </span><span class="go">array([0.63696169, 0.26978671, 0.04097352])</span>

<span class="gp">In [9]: </span><span class="n">rg</span><span class="o">.</span><span class="n">random</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;f&#39;</span><span class="p">)</span>
<span class="gh">Out[9]: </span><span class="go">array([0.07524014, 0.01652753, 0.17526722], dtype=float32)</span>
</pre></div>
</div>
<ul>
<li><p>Optional <code class="docutils literal notranslate"><span class="pre">out</span></code> argument that allows existing arrays to be filled for
select distributions</p>
<ul class="simple">
<li><p>Uniforms (<a class="reference internal" href="generated/numpy.random.Generator.random.html#numpy.random.Generator.random" title="numpy.random.Generator.random"><code class="xref py py-obj docutils literal notranslate"><span class="pre">random</span></code></a>)</p></li>
<li><p>Normals (<a class="reference internal" href="generated/numpy.random.Generator.standard_normal.html#numpy.random.Generator.standard_normal" title="numpy.random.Generator.standard_normal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_normal</span></code></a>)</p></li>
<li><p>Standard Gammas (<a class="reference internal" href="generated/numpy.random.Generator.standard_gamma.html#numpy.random.Generator.standard_gamma" title="numpy.random.Generator.standard_gamma"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_gamma</span></code></a>)</p></li>
<li><p>Standard Exponentials (<a class="reference internal" href="generated/numpy.random.Generator.standard_exponential.html#numpy.random.Generator.standard_exponential" title="numpy.random.Generator.standard_exponential"><code class="xref py py-obj docutils literal notranslate"><span class="pre">standard_exponential</span></code></a>)</p></li>
</ul>
<p>This allows multithreading to fill large arrays in chunks using suitable
BitGenerators in parallel.</p>
</li>
</ul>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [10]: </span><span class="n">existing</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>

<span class="gp">In [11]: </span><span class="n">rg</span><span class="o">.</span><span class="n">random</span><span class="p">(</span><span class="n">out</span><span class="o">=</span><span class="n">existing</span><span class="p">[:</span><span class="mi">2</span><span class="p">])</span>
<span class="gh">Out[11]: </span><span class="go">array([0.91275558, 0.60663578])</span>

<span class="gp">In [12]: </span><span class="nb">print</span><span class="p">(</span><span class="n">existing</span><span class="p">)</span>
<span class="go">[0.91275558 0.60663578 0.         0.        ]</span>
</pre></div>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>